본문으로 건너뛰기

SHIELDEX 연동 가이드

SHIELDEX File 무해화 시스템과 연동하는 프로세스를 설명합니다.

연동 방식은 크게 Callback 방식과 Polling 방식 두 가지를 지원합니다.

1. 전체 연동 프로세스​

무해화 연동은 API Key 발급 → 무해화 요청 → 결과 확인 → 파일 다운로드 4단계로 진행됩니다.

Step 1. 무해화 요청​

연동 시스템에서 SHIELDEX 서버로 파일을 전송하여 작업을 등록하고, Job ID를 발급받습니다.

Step 2. 결과 확인​

무해화 작업 완료 여부를 확인합니다. 두 가지 방식 중 하나를 선택할 수 있습니다.

Type A: Callback 수신 (권장)​

서버가 작업 완료 시 연동 시스템으로 결과를 통지합니다.

Type B: 상태 조회 (Polling)​

연동 시스템이 주기적으로 서버에 상태를 질의하여 완료를 확인합니다.

Step 3. 파일 다운로드​

무해화가 성공적으로 완료되면 파일을 다운로드합니다.

2. 연동 방식 선택​

Type A: Callback 방식 (권장)​

무해화 요청 시 callbackURL을 포함하여 보내면, 처리가 완료되는 즉시 해당 URL로 결과를 통지받는 방식입니다.

  • 장점 : 불필요한 조회 요청이 없고 실시간성이 보장됩니다.
  • 조건 : 연동 시스템 측에 결과를 수신할 수 있는 API 서버가 있어야 합니다.

Type B: Polling 방식​

무해화 요청 후, 주기적으로 상태 조회 API를 호출하여 완료 여부를 확인하는 방식입니다.

  • 장점 : 연동 시스템에 별도 수신 서버가 없어도 구현 가능합니다.
  • 주의 : 너무 잦은 요청(200ms 미만)은 서버 부하를 유발할 수 있습니다.

3. 단계별 상세 가이드​

Step 0. API Key 발급 (사전 준비)​

무해화 API를 호출하려면 먼저 연동 시스템을 등록하고 API Key를 발급받아야 합니다.

  1. 웹콘솔 → 정책 → 연동 시스템 정책 → 연동 시스템 등록
  2. 연동 시스템 이름, 레이블을 입력하고 등록하면 API Key가 자동 발급됩니다.
  3. (선택) 허용 IP를 등록하면 해당 IP에서만 요청이 가능합니다.
  4. 발급된 API Key는 모든 무해화 API 호출 시 Authorization: Bearer <API-KEY> 헤더에 포함합니다.

Step 1. 무해화 요청 (공통)​

파일과 메타데이터를 multipart/form-data로 전송하여 작업을 등록합니다.

API Key를 Authorization: Bearer 헤더에 포함하여 연동 시스템을 식별합니다.

Step 2. 결과 확인​

A. Callback 수신​

요청 시 설정한 URL로 JSON 결과가 도착합니다.

{
  "jobID": "test-job-001",
  "code": 0,
  "msg": "success",
  "logReason": 200000,
  "logReasonMsg": "파일 재구성 완료"
}

B. 상태 조회 (Polling)​

작업이 완료(code: 0, 1, 2)될 때까지 API를 주기적으로 호출합니다.

Step 3. 파일 다운로드​

결과 확인 단계에서 code: 0 (성공) 또는 code: 1 (예외/원본반입)인 경우 파일을 다운로드합니다.

4. 연동 시 주의사항​

  • UTF-8 인코딩 : 모든 요청의 문자셋은 UTF-8을 준수해야 합니다.
  • 다운로드 시점 : 상태 조회 API 응답이 완료(code: 0, 1) 상태일 때만 다운로드를 요청해야 합니다.